Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

IXFileFinder

Inherits From:	Object

Conforms To:	IXBlockAndStoreAccess
IXNameAndFileAccess
IXFileFinderConfiguration
IXFileFinderQueryAndUpdate
NXReference (Mach Kit)

Declared In:	indexing/IXFileFinder.h

Class Description

IXFileFinder answers queries against file attributes over a file system subtree, and can maintain indexes to improve query performance.  IXFileFinder manipulates instances of the IXFileRecord class as proxies for the actual files; queries return IXPostingLists containing IXFileRecords representing the selected files.  When used with an IXStore or IXStoreFile, IXFileFinder uses a private instance of the IXRecordManager class to store and index the IXFileRecords; this permits the efficient resolution of many queries without requiring the file system subtree to be scanned every time a query is performed.

IXFileFinder is completely thread-safe; it supports multiple asynchronous queries by programmer-supplied threads without conflict, and also provides an asynchronous index updating mechanism managed by a single, private background thread.

The functionality of IXFileFinder is primarily described in its two protocol specifications,  IXFileFinderConfiguration and IXFileFinderQueryAndUpdate, which anticipate its use with NEXTSTEP's Distributed Object facility.  This class specification documents only the initialization methods.

Instance Variables

unsigned int references;

List *attributeParsers;

id recordManager;

NXHashTable *ignoredNames;

NXHashTable *ignoredTypes;

char *rootPath;

unsigned int commitDelay;

struct {
	unsigned int crossesDeviceChanges:1;
	unsigned int followsSymbolicLinks:1;
	unsigned int generatesDescriptions:1;
	unsigned int updatesAutomatically:1;
	unsigned int scansForModifiedFiles:1;
	unsigned int removesAutomatically:1;
} booleanOptions;

references	The reference count.

attributeParsers	A List of IXAttributeParsers used to parse files.

recordManager	The object that manages the file records.

ignoredNames	The names of files that are ignored by the IXFileFinder.

ignoredTypes	The types of files that are ignored by the IXFileFinder.

rootPath	The root directory of the IXFileFinder.  This is considered the base of the subtree for which queries can be made.

commitDelay	The delay in seconds between consecutive transaction commitments during index update.

booleanOptions.crossesDeviceChanges
YES if the IXFileFinder addresses files on physical devices other than the one its primary directory is on.  NO by default.

booleanOptions.followsSymbolicLinks
YES if the IXFileFinder follows symbolic links.  NO by default.

booleanOptions.generatesDescriptions
YES if the IXFileFinder automatically generates descriptions for IXFileRecords from the file contents.  NO by default.

booleanOptions.updatesAutomatically
YES if the IXFileFinder automatically queues out-of-date files for indexing when a query is performed.  YES by default.

booleanOptions.scansForModifiedFiles
YES if the IXFileFinder scans for modified files when a query is performed.  YES by default.

booleanOptions.removesAutomatically
YES if the IXFileFinder scans for deleted files when updating, removing their proxies from the index.  YES by default.

Adopted Protocols

IXBlockAndStoreAccess	- initInStore:
- initFromBlock:inStore:
+ freeFromBlock:inStore:
- freeFromStore
- getBlock:andStore:

IXNameAndFileAccess	- initWithName:inFile:
- initFromName:inFile:forWriting:
+ freeFromName:inFile:
- freeFromStore
- getName:andFile:

IXFileFinderConfiguration	- setAttributeParsers:
- getAttributeParsers:
- setCrossesDeviceChanges:
- crossesDeviceChanges
- setFollowsSymbolicLinks:
- followsSymbolicLinks
- setGeneratesDescriptions:
- generatesDescriptions
- setIgnoredNames:
- ignoredNames
- setIgnoredTypes:
- ignoredTypes
- setScansForModifiedFiles:
- scansForModifiedFiles
- setUpdatesAutomatically:
- updatesAutomatically

IXFileFinderQueryAndUpdate	- rootPath
- recordManager
- performQuery:atPath:forSender:
- stopQueryForSender:
- updateIndexAtPath:
- isUpdating
- suspendUpdating
- resumeUpdating
- clean
- reset

NXReference	- references
- addReference
- free

Method Types

Initializing an IXFileFinder	- initInStore:atPath:
- initFromBlock:inStore:atPath:
- initWithName:inFile:atPath:
- initWithName:inFile:forWriting:atPath:

Instance Methods

initFromBlock:inStore:

- initFromBlock:(unsigned int)aHandle inStore:(IXStore *)aStore

Initializes a newly allocated IXFileFinder as initFromBlock:inStore:atPath: with a path argument of NULL.  This method is useful for opening an IXFileFinder whose root directory hasn't changed, which is usually the case.

See also:  - initFromBlock:inStore:atPath:

initFromBlock:inStore:atPath:

- initFromBlock:(unsigned int)aHandle
inStore:(IXStore *)aStore
atPath:(const char *)path

Initializes a newly allocated IXFileFinder by opening it from data stored in the block of aStore identified by aHandle.  This data should have been created by a previous instance of IXFileFinder.  The IXFileFinder's root path is reset to path; it will search for files within the subtree rooted at that directory.  path may be an absolute or relative pathname.  If path is NULL, the root path remains unchanged from its previous value.  The root path may not be changed after initialization.  Returns self.

This is the designated initializer for opening a pre-existing IXFileFinder with the IXBlockAndStoreAccess protocol.

See also:  - initInStore:atPath:, - initWithName:inFile:atPath:, IXBlockAndStoreAccess protocol

initFromName:inFile:forWriting:

- initFromName:(const char *)aName
inFile:(const char *)filename
forWriting:(BOOL)flag

Initializes a newly allocated IXFileFinder as initFromName:inFile:forWriting:atPath: with a path argument of NULL.  This method is useful for opening an IXFileFinder whose root directory hasn't changed, which is usually the case.

See also:  - initFromName:inFile:forWriting:atPath:

initFromName:inFile:forWriting:atPath:

- initFromName:(const char *)aName
inFile:(const char *)filename
forWriting:(BOOL)flag
atPath:(const char *)path

Initializes a newly allocated IXFileFinder by opening it from data stored under aName in filename by a previous instance.  The IXFileFinder's root path is reset to path; it will search for files within the subtree rooted at that directory.  path can be an absolute or relative pathname, or it can be NULL, in which case the IXFileFinder's root path remains unchanged.  The root path may not subsequently be changed unless the IXFileFinder is freed and then reopened.  If flag is YES, filename is opened for reading and writing, and the IXFileFinder is initialized to build and update its index; if flag is NO, filename is opened for reading only.  Returns self if successful, or nil if flag is YES and filename can't be written or created.

An IXFileFinder opened for reading only can be modified; however, the changes occur only in memory, and are never written to disk.  This can be useful for keeping an index up-to-date until the application terminates, without affecting the original file.

This is the designated initializer for opening a pre-existing IXFileFinder with the IXNameAndFileAccess protocol.  Note that the underlying IXStoreFile is opened by the IXFileFinder when this method is used, and that it will be closed when the IXFileFinder is freed.

See also:  - initWithName:inFile:atPath:, IXNameAndFileAccess protocol

initInStore:

- initInStore:(IXStore *)aStore

Initializes a newly allocated IXFileFinder as initInStore:atPath: with a path argument of NULL.

See also:  - initInStore:atPath:

initInStore:atPath:

- initInStore:(IXStore *)aStore atPath:(const char *)path

Initializes a newly allocated IXFileFinder in aStore, to search for files in the subtree rooted at the directory named path.  path is considered the root path for the IXFileFinder, and can be an absolute or relative pathname.  If path is NULL, the program's working directory is used.  The root path may not be changed after initialization.  If aStore is nil, then the IXFileFinder won't attempt to maintain indexes on file attributes using IXRecordManager.  This doesn't affect query semantics in any way; an IXFileFinder initialized without an IXStore will return the same query results as an IXFileFinder initialized with an IXStore.  The presence or absence of an IXStore merely affects query performance.  Returns self.

This is the designated initializer for creating new IXFileFinders with the IXBlockAndStoreAccess protocol.

See also:  - initFromBlock:inStore:atPath:, - initWithName:inFile:atPath:, - initWithName:inFile:forWriting:atPath:, IXBlockAndStoreAccess protocol

initWithName:inFile:

- initWithName:(const char *)aName inFile:(const char *)filename

Initializes a newly allocated IXFileFinder as initWithName:inFile:atPath:, with a path argument of NULL.

See also:  - initWithName:inFile:atPath:

initWithName:inFile:atPath:

- initWithName:(const char *)aName
inFile:(const char *)filename
atPath:(const char *)path

Initializes the IXFileFinder as a store file client named aName in the store file filename.  If filename doesn't exist, it's created.  The IXFileFinder will search for files in the subtree rooted at the directory named path, which is considered the root path for the IXFileFinder.  path can be an absolute or relative pathname  If path is NULL, the current working directory will be used.  The root path may not be changed after initialization.  filename is opened for writing and reading, so that indexes can be created, updated, and cleaned.  Returns self.

This is the designated initializer for creating new IXFileFinders with the IXNameAndFileAccess protocol.

See also:  - initInStore:atPath:, - initFromBlock:inStore:atPath:, - initWithName:inFile:forWriting:atPath:, IXNameAndFileAccess protocol